C++ API Reference¶

using SendFileCallback = std::function<void(OBFileTranState state, const char *message, uint8_t percent)>

Callback function for file transfer status updates.

Param state: The file transfer status.
Param message: Status information.
Param percent: The percentage of the file that has been transferred.

using DeviceUpgradeCallback = std::function<void(OBUpgradeState state, const char *message, uint8_t percent)>

Callback function for device upgrade status updates.

Param state: The device upgrade status.
Param message: Status information.
Param percent: The percentage of the upgrade that has been completed.

using DeviceStateChangedCallback = std::function<void(OBDeviceState state, const char *message)>

Callback function for device status updates.

Param state: The device status.
Param message: Status information.

using GetDataCallback = std::function<void(OBDataTranState state, OBDataChunk *dataChunk)>

Callback function for getting raw data property data when data and progress callbacks are made.

Param dataChunk: The data chunk.
Param state: The status of getting the data.

using SetDataCallback = std::function<void(OBDataTranState state, uint8_t percent)>

Callback function for setting the raw data property when progress callbacks are made.

Param percent: The progress percentage.
Param state: The status of setting the data.

namespace ob

Typedefs

typedef std::function<void(std::shared_ptr<Frame>)> FilterCallback: A callback function that takes a shared pointer to a Frame object as its argument.

typedef std::function<void(void *buffer, void *context)> BufferDestroyCallback

typedef std::function<void(std::shared_ptr<FrameSet> frame)> FrameSetCallback

using PlaybackCallback = std::function<void(std::shared_ptr<Frame> frame)>

using MediaStateCallback = std::function<void(OBMediaState state)>

using FrameCallback = std::function<void(std::shared_ptr<Frame> frame)>

Callback function for frame data.

Param frame: The frame data.

class AccelFrame : public ob::Frame

#include <Frame.hpp>

Define the AccelFrame class, which inherits from the Frame class.

Public Functions

OBAccelValue value()

Get the accelerometer frame data.

Returns: OBAccelValue The accelerometer frame data

float temperature()

Get the temperature when the frame was sampled.

Returns: float The temperature value

class AccelStreamProfile : public ob::StreamProfile

#include <StreamProfile.hpp>

Class representing an accelerometer stream profile.

Public Functions

OBAccelFullScaleRange fullScaleRange() const

Return the full scale range.

Returns: OBAccelFullScaleRange Return the scale range value.

OBAccelSampleRate sampleRate() const

Return the sampling frequency.

Returns: OBAccelFullScaleRange Return the sampling frequency.

class CameraParamList

#include <Device.hpp>

Class representing a list of camera parameters.

Public Functions

uint32_t count()

Get the number of camera parameter groups.

Returns: uint32_t the number of camera parameter groups

OBCameraParam getCameraParam(uint32_t index)

Get the camera parameters for the specified index.

Parameters: index – the index of the parameter group
Returns: OBCameraParam the corresponding group parameters

class ColorFrame : public ob::VideoFrame: #include <Frame.hpp>

class CompressionFilter : public ob::Filter

#include <Filter.hpp>

The CompressionFilter class is a subclass of Filter that performs compression.

Public Functions

void setCompressionParams(OBCompressionMode mode, void *params)

Set the compression parameters.

Parameters

mode – The compression mode: OB_COMPRESSION_LOSSLESS or OB_COMPRESSION_LOSSY.
params – The compression parameters. When mode is OB_COMPRESSION_LOSSLESS, params is NULL.

class Config

#include <Pipeline.hpp>

Config class for configuring pipeline parameters.

The Config class provides an interface for configuring pipeline parameters.

Public Functions

Config(): Construct a new Config object.

~Config() noexcept: Destroy the Config object.

void enableStream(std::shared_ptr<StreamProfile> streamProfile)

Enable a stream to be used in the pipeline.

Parameters: streamProfile – The stream configuration to be enabled

void enableAllStream(): Enable all streams to be used in the pipeline.

void disableStream(OBStreamType streamType)

Disable a stream to be used in the pipeline.

Parameters: streamType – The stream configuration to be disabled

void disableAllStream(): Disable all streams to be used in the pipeline.

void setAlignMode(OBAlignMode mode)

Set the alignment mode.

Parameters: mode – The alignment mode

void setDepthScaleRequire(bool enable)

Set whether the depth needs to be scaled after setting D2C.

Parameters: enable – Whether scaling is required

void setD2CTargetResolution(uint32_t d2cTargetWidth, uint32_t d2cTargetHeight)

Set the D2C target resolution.

The D2C target resolution is applicable to cases where the color stream is not enabled using the OrbbecSDK and the depth needs to be D2C.

Note

When you use OrbbecSDK to enable the color stream, you also use this interface to set the D2C target resolution. The configuration of the enabled Color stream is preferred for D2C.

Parameters

d2cTargetWidth – The D2C target width resolution
d2cTargetHeight – The D2C target height resolution

class Context

#include <Context.hpp>

Public Types

using LogCallback = std::function<void(OBLogSeverity severity, const char *logMsg)>

Log output callback function.

Param severity: The current callback log level.
Param logMsg: The log message.

Public Functions

Context(const char *configPath = ""): The Context class is a management class that describes the runtime of the SDK. It is responsible for applying and releasing resources for the SDK. The context has the ability to manage multiple devices, enumerate devices, monitor device callbacks, and enable functions such as multi-device synchronization.

std::shared_ptr<DeviceList> queryDeviceList()

Queries the enumerated device list.

Returns: std::shared_ptr<DeviceList> A pointer to the device list class.

void enableNetDeviceEnumeration(bool enable)

enable or disable net device enumeration.

after enable, the net device will be discovered automatically and can be retrieved by queryDeviceList. The default state can be set in the configuration file.

Attention: Net device enumeration by gvcp protocol, if the device is not in the same subnet as the host, it will be discovered but cannot be connected.

Parameters: enable – [out] true to enable, false to disable

std::shared_ptr<Device> createNetDevice(const char *address, uint16_t port)

Creates a network device object.

Parameters

address – The IP address.
port – The port.

Returns

std::shared_ptr<Device> The created device object.

void changeNetDeviceIpConfig(const char *deviceUid, const OBNetIpConfig &config)

Changes the IP configuration of a network device.

Parameters

deviceUid – The device unique ID, which is the network device MAC address. It can be obtained through the DeviceList::uid() function.
config – The new IP configuration.

void setDeviceChangedCallback(DeviceChangedCallback callback)

Set the device plug-in callback function.

Parameters: callback – The function triggered when the device is plugged and unplugged.

void enableDeviceClockSync(uint64_t repeatInterval)

Activates device clock synchronization to synchronize the clock of the host and all created devices (if supported).

Parameters: repeatInterval – The interval for auto-repeated synchronization, in milliseconds. If the value is 0, synchronization is performed only once.

void freeIdleMemory(): Frees idle memory from the internal frame memory pool.

Public Static Functions

static void setLoggerSeverity(OBLogSeverity severity)

Set the level of the global log, which affects both the log level output to the terminal and output to the file.

Parameters: severity – The log output level.

static void setLoggerToFile(OBLogSeverity severity, const char *directory)

Set log output to a file.

Parameters

severity – The log level output to the file.
directory – The log file output path. If the path is empty, the existing settings will continue to be used (if the existing configuration is also empty, the log will not be output to the file).

static void setLoggerToConsole(OBLogSeverity severity)

Set log output to the terminal.

Parameters: severity – The log level output to the terminal.

static void setLoggerToCallback(OBLogSeverity severity, LogCallback callback)

Set the logger to callback.

Parameters

severity – The callback log level.
callback – The callback function.

static void loadLicense(const char *filePath, const char *key = OB_DEFAULT_DECRYPT_KEY)

Loads a license file.

Parameters

filePath – The license file path.
key – The decryption key.

static void loadLicenseFromData(const char *data, uint32_t dataLen, const char *key = OB_DEFAULT_DECRYPT_KEY)

Loads a license from data.

Parameters

data – The license data.
dataLen – The license data length.
key – The decryption key.

class DecompressionFilter : public ob::Filter: #include <Filter.hpp>
The DecompressionFilter class is a subclass of Filter that performs decompression.

class DepthFrame : public ob::VideoFrame

#include <Frame.hpp>

Public Functions

float getValueScale()

Get the value scale of the depth frame. The pixel value of depth frame is multiplied by the scale to give a depth value in millimeters. For example, if valueScale=0.1 and a certain coordinate pixel value is pixelValue=10000, then the depth value = pixelValue*valueScale = 10000*0.1=1000mm.

Returns: float The scale.

class Device

#include <Device.hpp>

Public Functions

Device(std::unique_ptr<DeviceImpl> impl): Describe the entity of the RGBD camera, representing a specific model of RGBD camera.

std::shared_ptr<DeviceInfo> getDeviceInfo()

Get device information.

Returns: std::shared_ptr<DeviceInfo> return device information

std::shared_ptr<SensorList> getSensorList()

Get device sensor list.

Returns: std::shared_ptr<SensorList> return the sensor list

std::shared_ptr<Sensor> getSensor(OBSensorType type)

Get specific type of sensor if device not open, SDK will automatically open the connected device and return to the instance.

Returns: std::shared_ptr<Sensor> return the sensor example, if the device does not have the device,return nullptr

void setIntProperty(OBPropertyID propertyId, int32_t property)

Set int type of device property.

Parameters

propertyId – Property id
property – Property to be set

void setFloatProperty(OBPropertyID propertyId, float property)

Set float type of device property.

Parameters

propertyId – Property id
property – Property to be set

void setBoolProperty(OBPropertyID propertyId, bool property)

Set bool type of device property.

Parameters

propertyId – Property id
property – Property to be set

int32_t getIntProperty(OBPropertyID propertyId)

Get int type of device property.

Parameters: propertyId – Property id
Returns: int32_t Property to get

float getFloatProperty(OBPropertyID propertyId)

Get float type of device property.

Parameters: propertyId – Property id
Returns: float Property to get

bool getBoolProperty(OBPropertyID propertyId)

Get bool type of device property.

Parameters: propertyId – Property id
Returns: bool Property to get

OBIntPropertyRange getIntPropertyRange(OBPropertyID propertyId)

Get int type device property range (including current value and default value)

Parameters: propertyId – Property id
Returns: OBIntPropertyRange Property range

OBFloatPropertyRange getFloatPropertyRange(OBPropertyID propertyId)

Get float type device property range((including current value and default value)

Parameters: propertyId – Property id
Returns: OBFloatPropertyRange Property range

OBBoolPropertyRange getBoolPropertyRange(OBPropertyID propertyId)

Get bool type device property range (including current value and default value)

Parameters: propertyId – The ID of the property
Returns: OBBoolPropertyRange The range of the property

void writeAHB(uint32_t reg, uint32_t mask, uint32_t value)

Write to an AHB register.

Parameters

reg – The register to write to
mask – The mask to apply
value – The value to write

void readAHB(uint32_t reg, uint32_t mask, uint32_t *value)

Read from an AHB register.

Parameters

reg – The register to read from
mask – The mask to apply
value – The value to return

void writeI2C(uint32_t moduleId, uint32_t reg, uint32_t mask, uint32_t value)

Write to an I2C register.

Parameters

moduleId – The ID of the I2C module to write to
reg – The register to write to
mask – The mask to apply
value – The value to write

void readI2C(uint32_t moduleId, uint32_t reg, uint32_t mask, uint32_t *value)

Read from an I2C register.

Parameters

moduleId – The ID of the I2C module to read from
reg – The register to read from
mask – The mask to apply
value – The value to return

void writeFlash(uint32_t offset, const void *data, uint32_t dataSize, SetDataCallback callback, bool async = false)

Set the properties for writing to Flash.

Parameters

offset – The offset address in Flash
data – The data to write
dataSize – The size of the data to write
callback – The callback for write progress
async – Whether to execute asynchronously

void readFlash(uint32_t offset, uint32_t dataSize, GetDataCallback callback, bool async = false)

Read a property from Flash.

Parameters

offset – The offset address in Flash
dataSize – The size of the property to read
callback – The callback for read progress and data
async – Whether to execute asynchronously

void writeCustomerData(const void *data, uint32_t dataSize)

Set the customer data type of a device property.

Parameters

data – The data to set
dataSize – The size of the data to set,the maximum length cannot exceed 65532 bytes.

void readCustomerData(void *data, uint32_t *dataSize)

Get the customer data type of a device property.

Parameters

data – The property data obtained
dataSize – The size of the data obtained

void setRawData(OBPropertyID propertyId, const void *data, uint32_t dataSize, SetDataCallback callback, bool async = false)

Set the raw data type of a device property (with asynchronous callback)

Parameters

propertyId – The ID of the property
data – The data to set
dataSize – The size of the data to set
callback – The callback for set progress
async – Whether to execute asynchronously

void getRawData(OBPropertyID propertyId, GetDataCallback callback, bool async = false)

Get the raw data type of a device property (with asynchronous callback)

Parameters

propertyId – The ID of the property
callback – The callback for getting the data and progress
async – Whether to execute asynchronously

void setStructuredData(OBPropertyID propertyId, const void *data, uint32_t dataSize)

Set the structured data type of a device property.

Parameters

propertyId – The ID of the property
data – The data to set
dataSize – The size of the data to set

void getStructuredData(OBPropertyID propertyId, void *data, uint32_t *dataSize)

Get the structured data type of a device property.

Parameters

propertyId – The ID of the property
data – The property data obtained
dataSize – The size of the data obtained

void setStructuredDataExt(OBPropertyID propertyId, std::shared_ptr<OBDataBundle> dataBundle, SetDataCallback callback)

Set the structured data type of a device property (with extended data bundle)

Parameters

propertyId – The ID of the property
dataBundle – The target data bundle
callback – The callback for setting

std::shared_ptr<OBDataBundle> getStructuredDataExt(OBPropertyID propertyId)

Get the structured data type of a device property (with extended data bundle)

Parameters: propertyId – The ID of the property
Returns: The data bundle

OBProtocolVersion getProtocolVersion()

Get the property protocol version.

Returns: The protocol version

OBCmdVersion getCmdVersion(OBPropertyID propertyId)

Get the cmdVersion of a property.

Parameters: propertyId – The ID of the property
Returns: The cmdVersion

uint32_t getSupportedPropertyCount()

Get the number of properties supported by the device.

Returns: The number of supported properties

OBPropertyItem getSupportedProperty(uint32_t index)

Get the supported properties of the device.

Parameters: index – The index of the property
Returns: The type of supported property

bool isPropertySupported(OBPropertyID propertyId, OBPermissionType permission)

Check if a property permission is supported.

Parameters

propertyId – The ID of the property
permission – The read and write permissions to check

Returns

Whether the property permission is supported

void deviceUpgrade(const char *filePath, DeviceUpgradeCallback callback, bool async = true)

Upgrade the device firmware.

Parameters

filePath – Firmware path
callback – Firmware upgrade progress and status callback
async – Whether to execute asynchronously

void deviceUpgradeFromData(const char *fileData, uint32_t fileSize, DeviceUpgradeCallback callback, bool async = true)

Upgrade the device firmware.

Parameters

fileData – Firmware file data
fileSize – Firmware file size
callback – Firmware upgrade progress and status callback
async – Whether to execute asynchronously

void sendFile(const char *filePath, const char *dstPath, SendFileCallback callback, bool async = true)

Send files to the specified path on the device side [Asynchronouscallback].

Parameters

filePath – Original file path
dstPath – Accept the save path on the device side
callback – File transfer callback
async – Whether to execute asynchronously

OBDeviceState getDeviceState()

Get the current state.

Returns: OBDeviceState device state information

void setDeviceStateChangedCallback(DeviceStateChangedCallback callback)

Set the device state changed callbacks.

Parameters: callback – The callback function that is triggered when the device status changes (for example, the frame rate is automatically reduced or the stream is closed due to high temperature, etc.)

bool activateAuthorization(const char *authCode)

Verify device authorization code.

Parameters: authCode – Authorization code
Returns: bool whether the activation is successful

void writeAuthorizationCode(const char *authCodeStr)

Write authorization code.

Parameters: authCodeStr – [in] Authorization code

std::shared_ptr<CameraParamList> getCalibrationCameraParamList()

Get the original parameter list of camera calibration saved in the device.

Attention: The parameters in the list do not correspond to the current open-current configuration. You need to select the parameters according to the actual situation, and may need to do scaling, mirroring and other processing. Non-professional users are recommended to use the Pipeline::getCameraParam() interface.

Returns: std::shared_ptr<CameraParamList> camera parameter list

OBDepthWorkMode getCurrentDepthWorkMode()

Get current depth work mode.

Returns: ob_depth_work_mode Current depth work mode

OBStatus switchDepthWorkMode(const OBDepthWorkMode &workMode)

Switch depth work mode by OBDepthWorkMode. Prefer invoke switchDepthWorkMode(const char *modeName) to switch depth mode when known the complete name of depth work mode.

Parameters: workMode – [in] Depth work mode come from ob_depth_work_mode_list which return by ob_device_get_depth_work_mode_list

OBStatus switchDepthWorkMode(const char *modeName)

Switch depth work mode by work mode name.

Parameters: modeName – [in] Depth work mode name which equals to OBDepthWorkMode.name

std::shared_ptr<OBDepthWorkModeList> getDepthWorkModeList()

Request support depth work mode list.

Returns: OBDepthWorkModeList list of ob_depth_work_mode

void reboot()

Device restart.

Attention: The device will be disconnected and reconnected. After the device is disconnected, the access to the Device object interface may be abnormal. Please delete the object directly and obtain it again after the device is reconnected.

void reboot(uint32_t delayMs)

Device restart delay mode.

Attention: The device will be disconnected and reconnected. After the device is disconnected, the access to the Device object interface may be abnormal. Please delete the object directly and obtain it again after the device is reconnected. Support devices: Gemini2 L

Parameters: delayMs – [in] Time unit：ms。delayMs == 0：No delay；delayMs > 0, Delay millisecond connect to host device after reboot

DEPRECATED uint64_t syncDeviceTime ()

Synchronize the device time (synchronize local system time to device)

Deprecated:: This interface is deprecated, please use timerSyncWithHost instead.

Returns: The command (round trip time, rtt)

DEPRECATED OBDeviceSyncConfig getSyncConfig ()

get the current device synchronization configuration

Device synchronization: including exposure synchronization function and multi-camera synchronization function of different sensors within a single machine

Deprecated:: This interface is deprecated, please use getMultiDeviceSyncConfig instead.

Returns: OBDeviceSyncConfig return the device synchronization configuration

DEPRECATED void setSyncConfig (const OBDeviceSyncConfig &deviceSyncConfig)

Set the device synchronization configuration.

Used to configure the exposure synchronization function and multi-camera synchronization function of different sensors in a single machine

Deprecated:: This interface is deprecated, please use setMultiDeviceSyncConfig instead.

Attention: Calling this function will directly write the configuration to the device Flash, and it will still take effect after the device restarts. To avoid affecting the Flash lifespan, do not update the configuration frequently.

Parameters: deviceSyncConfig – Device synchronization configuration

uint16_t getSupportedMultiDeviceSyncModeBitmap()

Get the supported multi device sync mode bitmap of the device.

For example, if the return value is 0b00001100, it means the device supports OB_MULTI_DEVICE_SYNC_MODE_PRIMARY and OB_MULTI_DEVICE_SYNC_MODE_SECONDARY. User can check the supported mode by the code:

if(supported_mode_bitmap & OB_MULTI_DEVICE_SYNC_MODE_FREE_RUN){
   //support OB_MULTI_DEVICE_SYNC_MODE_FREE_RUN
}
if(supported_mode_bitmap & OB_MULTI_DEVICE_SYNC_MODE_STANDALONE){
  //support OB_MULTI_DEVICE_SYNC_MODE_STANDALONE
}
// and so on

Returns: uint16_t return the supported multi device sync mode bitmap of the device.

void setMultiDeviceSyncConfig(const OBMultiDeviceSyncConfig &config)

set the multi device sync configuration of the device.

Parameters: config – [in] The multi device sync configuration.

OBMultiDeviceSyncConfig getMultiDeviceSyncConfig()

get the multi device sync configuration of the device.

Returns: OBMultiDeviceSyncConfig return the multi device sync configuration of the device.

void triggerCapture()

send the capture command to the device.

The device will start one time image capture after receiving the capture command when it is in the OB_MULTI_DEVICE_SYNC_MODE_SOFTWARE_TRIGGERING

Attention: The frequency of the user call this function multiplied by the number of frames per trigger should be less than the frame rate of the stream. The number of frames per trigger can be set by framesPerTrigger.
Attention: For some models，receive and execute the capture command will have a certain delay and performance consumption, so the frequency of calling this function should not be too high, please refer to the product manual for the specific supported frequency.
Attention: If the device is not in the OB_MULTI_DEVICE_SYNC_MODE_HARDWARE_TRIGGERING mode, device will ignore the capture command.

void setTimestampResetConfig(const OBDeviceTimestampResetConfig &config): set the timestamp reset configuration of the device.

OBDeviceTimestampResetConfig getTimestampResetConfig()

get the timestamp reset configuration of the device.

Returns: OBDeviceTimestampResetConfig return the timestamp reset configuration of the device.

void timestampReset()

send the timestamp reset command to the device.

The device will reset the timer for calculating the timestamp for output frames to 0 after receiving the timestamp reset command when the timestamp reset function is enabled. The timestamp reset function can be enabled by call ob_device_set_timestamp_reset_config.

Before calling this function, user should call ob_device_set_timestamp_reset_config to disable the timestamp reset function (It is not required for some models, but it is still recommended to do so for code compatibility).

Attention: If the stream of the device is started, the timestamp of the continuous frames output by the stream will jump once after the timestamp reset.
Attention: Due to the timer of device is not high-accuracy, the timestamp of the continuous frames output by the stream will drift after a long time. User can call this function periodically to reset the timer to avoid the timestamp drift, the recommended interval time is 60 minutes.

void timerSyncWithHost()

synchronize the timer of the device with the host.

After calling this function, the timer of the device will be synchronized with the host. User can call this function to multiple devices to synchronize all timers of the devices.

Attention: If the stream of the device is started, the timestamp of the continuous frames output by the stream will may jump once after the timer sync.
Attention: Due to the timer of device is not high-accuracy, the timestamp of the continuous frames output by the stream will drift after a long time. User can call this function periodically to synchronize the timer to avoid the timestamp drift, the recommended interval time is 60 minutes.

class DeviceInfo

#include <Device.hpp>

A class describing device information, representing the name, id, serial number and other basic information of an RGBD camera.

Public Functions

const char *name()

Get device name.

Returns: const char * return the device name

int pid()

Get the pid of the device.

Returns: int return the pid of the device

int vid()

Get the vid of the device.

Returns: int return the vid of the device

const char *uid()

Get system assigned uid for distinguishing between different devices.

Returns: const char * return the uid of the device

const char *serialNumber()

Get the serial number of the device.

Returns: const char * return the serial number of the device

const char *firmwareVersion()

Get the version number of the firmware.

Returns: const char* return the version number of the firmware

DEPRECATED const char * usbType ()

Get the USB connection type of the device (DEPRECATED)

Returns: const char* the USB connection type of the device

const char *connectionType()

Get the connection type of the device.

Returns: const char* the connection type of the device，currently supports：”USB”, “USB1.0”, “USB1.1”, “USB2.0”, “USB2.1”, “USB3.0”, “USB3.1”, “USB3.2”, “Ethernet”

const char *ipAddress()

Get the IP address of the device.

Attention: Only valid for network devices, otherwise it will return “0.0.0.0”.

Returns: const char* the IP address of the device, such as “192.168.1.10”

const char *hardwareVersion()

Get the version number of the hardware.

Returns: const char* the version number of the hardware

const char *supportedMinSdkVersion()

Get the minimum version number of the SDK supported by the device.

Returns: const char* the minimum SDK version number supported by the device

const char *extensionInfo()

Get information about extensions obtained from SDK supported by the device.

Returns: const char* Returns extended information about the device

const char *asicName()

Get chip type name.

Returns: const char* the chip type name

OBDeviceType deviceType()

Get the device type.

Returns: OBDeviceType the device type

class DeviceList

#include <Device.hpp>

Class representing a list of devices.

Public Functions

uint32_t deviceCount()

Get the number of devices in the list.

Returns: uint32_t the number of devices in the list

DEPRECATED const char * name (uint32_t index)

Get the name of the device at the specified index (DEPRECATED)

Parameters: index – the index of the device
Returns: int the name of the device

int pid(uint32_t index)

Get the PID of the device at the specified index.

Parameters: index – the index of the device
Returns: int the PID of the device

int vid(uint32_t index)

Get the VID of the device at the specified index.

Parameters: index – the index of the device
Returns: int the VID of the device

const char *uid(uint32_t index)

Get the UID of the device at the specified index.

Parameters: index – the index of the device
Returns: const char* the UID of the device

const char *serialNumber(uint32_t index)

Get the serial number of the device at the specified index.

Parameters: index – the index of the device
Returns: const char* the serial number of the device

const char *connectionType(uint32_t index)

Get device connection type.

Parameters: index – device index
Returns: const char* returns connection type，currently supports：”USB”, “USB1.0”, “USB1.1”, “USB2.0”, “USB2.1”, “USB3.0”, “USB3.1”, “USB3.2”, “Ethernet”

const char *ipAddress(uint32_t index)

get the ip address of the device at the specified index

Attention: Only valid for network devices, otherwise it will return “0.0.0.0”.

Parameters: index – the index of the device
Returns: const char* the ip address of the device

std::shared_ptr<Device> getDevice(uint32_t index)

Get the device object at the specified index.

Attention: If the device has already been acquired and created elsewhere, repeated acquisition will throw an exception

Parameters: index – the index of the device to create
Returns: std::shared_ptr<Device> the device object

std::shared_ptr<Device> getDeviceBySN(const char *serialNumber)

Get the device object with the specified serial number.

Attention: If the device has already been acquired and created elsewhere, repeated acquisition will throw an exception

Parameters: serialNumber – the serial number of the device to create
Returns: std::shared_ptr<Device> the device object

std::shared_ptr<Device> getDeviceByUid(const char *uid)

Get the specified device object from the device list by uid.

On Linux platform, the uid of the device is composed of bus-port-dev, for example 1-1.2-1. But the SDK will remove the dev number and only keep the bus-port as the uid to create the device, for example 1-1.2, so that we can create a device connected to the specified USB port. Similarly, users can also directly pass in bus-port as uid to create device.

Attention: If the device has been acquired and created elsewhere, repeated acquisition will throw an exception

Parameters: uid – The uid of the device to be created
Returns: std::shared_ptr<Device> returns the device object

class Error

#include <Error.hpp>

Public Functions

const char *getMessage() const noexcept

Get the detailed error logs of SDK internal exceptions.

Returns: A C-style string containing the error message.

OBExceptionType getExceptionType() const noexcept

Get the exception type of the error, which can be used to determine which module is abnormal.

Returns: The OBExceptionType enum value.

const char *getName() const noexcept

Get the name of the error function.

Returns: A C-style string containing the name of the error function.

const char *getArgs() const noexcept

Get the parameter passed to the error interface.

Returns: A C-style string containing the error interface parameter.

class Filter

#include <Filter.hpp>

The Filter class is the base class for all filters in the SDK.

Subclassed by ob::CompressionFilter, ob::DecompressionFilter, ob::FormatConvertFilter, ob::PointCloudFilter

Public Functions

virtual void reset(): ReSet the filter, freeing the internal cache, stopping the processing thread, and clearing the pending buffer frame when asynchronous processing is used.

virtual std::shared_ptr<Frame> process(std::shared_ptr<Frame> frame)

Processes a frame synchronously.

Parameters: frame – The frame to be processed.
Returns: std::shared_ptr< Frame > The processed frame.

virtual void pushFrame(std::shared_ptr<Frame> frame)

Pushes the pending frame into the cache for asynchronous processing.

Parameters: frame – The pending frame. The processing result is returned by the callback function.

virtual void setCallBack(FilterCallback callback)

Set the callback function for asynchronous processing.

Parameters: callback – The processing result callback.

class FormatConvertFilter : public ob::Filter

#include <Filter.hpp>

The FormatConvertFilter class is a subclass of Filter that performs format conversion.

Public Functions

void setFormatConvertType(OBConvertFormat type)

Set the format conversion type.

Parameters: type – The format conversion type.

class Frame : public std::enable_shared_from_this<Frame>

#include <Frame.hpp>

Subclassed by ob::AccelFrame, ob::FrameSet, ob::GyroFrame, ob::PointsFrame, ob::VideoFrame

Public Functions

virtual OBFrameType type()

Get the type of frame.

Returns: OBFrameType The type of frame.

virtual OBFormat format()

Get the format of the frame.

Returns: OBFormat The format of the frame.

virtual uint64_t index()

Get the sequence number of the frame.

Returns: uint64_t The sequence number of the frame.

virtual void *data()

Get the frame data.

Returns: void* The frame data.

virtual uint32_t dataSize()

Get the size of the frame data.

Returns: uint32_t The size of the frame data. For point cloud data, this returns the number of bytes occupied by all point sets. To find the number of points, divide the dataSize by the structure size of the corresponding point type.

uint64_t timeStamp()

Get the hardware timestamp of the frame in milliseconds.

The hardware timestamp is the time point when the frame was captured by the device, on device clock domain.

Returns: uint64_t The hardware timestamp of the frame in milliseconds.

uint64_t timeStampUs()

Get the hardware timestamp of the frame in microseconds.

The hardware timestamp is the time point when the frame was captured by the device, on device clock domain.

Returns: uint64_t The hardware timestamp of the frame in microseconds.

uint64_t systemTimeStamp()

Get the system timestamp of the frame in milliseconds.

The system timestamp is the time point when the frame was received by the host, on host clock domain.

Returns: uint64_t The system timestamp of the frame in milliseconds.

template<typename T> bool is()

Check if the runtime type of the frame object is compatible with a given type.

Template Parameters: T – The given type.
Returns: bool The result.

template<typename T> inline std::shared_ptr<T> as()

Convert the frame object to a target type.

Template Parameters: T – The target type.
Returns: std::shared_ptr<T> The result. If it cannot be converted, an exception will be thrown.

class FrameHelper

#include <Frame.hpp>

Define the FrameHelper class.

Public Static Functions

static std::shared_ptr<Frame> createFrame(OBFrameType type, OBFormat format, uint32_t width, uint32_t height, uint32_t strideBytes)

Create a Frame object.

Parameters

type – [in] The type of frame. See OBFrameType.
format – [in] The format of the frame. See OBFormat.
width – [in] The width of the frame.
height – [in] The height of the frame.
strideBytes – [in] The stride of the frame in bytes. If strideBytes > 0, the frame data size = height * strideBytes. If strideBytes = 0, the frame datasize = height * width * pixelSize (pixelSize according to the format).

Returns

std::shared_ptr<Frame> The created frame object.

static std::shared_ptr<Frame> createFrameFromBuffer(OBFormat format, uint32_t width, uint32_t height, uint8_t *buffer, uint32_t bufferSize, BufferDestroyCallback destroyCallback, void *destroyCallbackContext)

Create a frame object based on an externally created buffer.

Parameters

format – [in] The format of the frame. See OBFormat.
width – [in] The width of the frame.
height – [in] The height of the frame.
buffer – [in] The frame object buffer
bufferSize – [in] The frame object buffer size
destroyCallback – [in] The frame object buffer destroy callback
destroyCallbackContext – [in] The frame object buffer destroy callback context

Returns

std::shared_ptr<Frame> The created frame object

static std::shared_ptr<FrameSet> createFrameSet()

Create an empty FrameSet object.

Returns: std::shared_ptr<Frame> The FrameSet object

static void pushFrame(std::shared_ptr<Frame> frameSet, OBFrameType frameType, std::shared_ptr<Frame> frame)

Add a frame of a specific type to the FrameSet.

Parameters

frameSet – The FrameSet object
frameType – The type of frame to add
frame – The frame object to add

static void setFrameSystemTimestamp(std::shared_ptr<Frame> frame, uint64_t systemTimestamp)

Set the system timestamp of the frame.

Parameters

frame – The frame object.
systemTimestamp – The system timestamp to set in milliseconds.

static void setFrameDeviceTimestamp(std::shared_ptr<Frame> frame, uint64_t deviceTimestamp)

Set the device timestamp of the frame.

Parameters

frame – The frame object.
deviceTimestamp – The device timestamp to set in milliseconds.

static void setFrameDeviceTimestampUs(std::shared_ptr<Frame> frame, uint64_t deviceTimestampUs)

Set the device timestamp of the frame.

Parameters

frame – The frame object.
deviceTimestampUs – The device timestamp to set in microseconds.

class FrameSet : public ob::Frame

#include <Frame.hpp>

Define the FrameSet class, which inherits from the Frame class.

Public Functions

uint32_t frameCount()

Get the number of frames in the FrameSet.

Returns: uint32_t The number of frames

std::shared_ptr<DepthFrame> depthFrame()

Get the depth frame in the FrameSet.

Returns: std::shared_ptr<DepthFrame> The depth frame

std::shared_ptr<ColorFrame> colorFrame()

Get the color frame in the FrameSet.

Returns: std::shared_ptr<ColorFrame> The color frame

std::shared_ptr<IRFrame> irFrame()

Get the infrared frame in the FrameSet.

Returns: std::shared_ptr<IRFrame> The infrared frame

std::shared_ptr<PointsFrame> pointsFrame()

Get the point cloud frame in the FrameSet.

Returns: std::shared_ptr<PointsFrame> The point cloud data frame

std::shared_ptr<Frame> getFrame(OBFrameType frameType)

Get a frame of a specific type from the FrameSet.

Parameters: frameType – The type of sensor
Returns: std::shared_ptr<Frame> The corresponding type of frame

std::shared_ptr<Frame> getFrame(int index)

Get a frame at a specific index from the FrameSet.

Parameters: index – The index of the frame
Returns: std::shared_ptr<Frame> The frame at the specified index

class GyroFrame : public ob::Frame

#include <Frame.hpp>

Define the GyroFrame class, which inherits from the Frame class.

Public Functions

OBGyroValue value()

Get the gyro frame data.

Returns: OBAccelValue The gyro frame data

float temperature()

Get the temperature when the frame was sampled.

Returns: float The temperature value

class GyroStreamProfile : public ob::StreamProfile

#include <StreamProfile.hpp>

Class representing a gyroscope stream profile.

Public Functions

OBGyroFullScaleRange fullScaleRange() const

Return the full scale range.

Returns: OBAccelFullScaleRange Return the scale range value.

OBGyroSampleRate sampleRate() const

Return the sampling frequency.

Returns: OBAccelFullScaleRange Return the sampling frequency.

class IRFrame : public ob::VideoFrame: #include <Frame.hpp>

class OBDepthWorkModeList

#include <Device.hpp>

Class representing a list of OBDepthWorkMode.

Public Functions

uint32_t count()

Get the number of OBDepthWorkMode objects in the list.

Returns: uint32_t the number of OBDepthWorkMode objects in the list

OBDepthWorkMode getOBDepthWorkMode(uint32_t index)

Get the OBDepthWorkMode object at the specified index.

Parameters: index – the index of the target OBDepthWorkMode object
Returns: OBDepthWorkMode the OBDepthWorkMode object at the specified index

const char *getName(uint32_t index)

Get the name of the depth work mode at the specified index.

Parameters: index – the index of the depth work mode
Returns: const char* the name of the depth work mode

OBDepthWorkMode operator[](uint32_t index)

Get the OBDepthWorkMode object at the specified index.

Parameters: index – the index of the target OBDepthWorkMode object
Returns: OBDepthWorkMode the OBDepthWorkMode object at the specified index

class Pipeline

#include <Pipeline.hpp>

Public Functions

Pipeline(): Pipeline is a high-level interface for applications, algorithms related RGBD data streams. Pipeline can provide alignment inside and synchronized FrameSet. Pipeline() no parameter version, which opens the first device in the list of devices connected to the OS by default. If the application has obtained the device through the DeviceList, opening the Pipeline() at this time will throw an exception that the device has been created.

Pipeline(std::shared_ptr<Device> device): Pipeline(std::shared_ptr< Device > device ) Function for multi-device operations. Multiple devices need to be obtained through DeviceList, and the device and pipeline are bound through this interface.

Pipeline(const char *filename)

Construct a pipeline for playback of recorded stream files.

Parameters: filename – The file path of the recorded stream file to be played back

~Pipeline() noexcept: Destroy the pipeline object.

void start(std::shared_ptr<Config> config)

Start the pipeline with configuration parameters.

Parameters: config – The parameter configuration of the pipeline

void start(std::shared_ptr<Config> config, FrameSetCallback callback)

Start the pipeline and set the frameset data callback.

Parameters

config – The parameter configuration of the pipeline
callback – The callback to be triggered when all frame data in the frameset arrives

void stop(): Stop the pipeline.

std::shared_ptr<Config> getConfig()

Get the pipeline configuration parameters.

Returns: std::shared_ptr<Config> The configured parameters

std::shared_ptr<FrameSet> waitForFrames(uint32_t timeout_ms)

Wait for frameset data.

Parameters: timeout_ms – The waiting timeout in milliseconds
Returns: std::shared_ptr<FrameSet> The waiting frameset data

std::shared_ptr<Device> getDevice()

Get the device object.

Returns: std::shared_ptr<Device> The device object

std::shared_ptr<Playback> getPlayback()

Get the playback object.

Returns: std::shared_ptr<Playback> The playback object

std::shared_ptr<StreamProfileList> getStreamProfileList(OBSensorType sensorType)

Get the stream profile of the specified sensor.

Parameters: sensorType – The type of sensor
Returns: std::shared_ptr<StreamProfileList> The stream profile list

void enableFrameSync(): Turn on frame synchronization.

void disableFrameSync(): Turn off frame synchronization.

OBCameraParam getCameraParam()

Get the camera parameters.

Note

If D2C is enabled, it will return the camera parameters after D2C. If not, it will return the default parameters.

Returns: OBCameraParam The camera parameters

OBCameraParam getCameraParamWithProfile(uint32_t colorWidth, uint32_t colorHeight, uint32_t depthWidth, uint32_t depthHeight)

Get camera parameters by entering color and depth resolution.

Attention: If D2C is enabled, it will return the camera parameters after D2C, if not, it will return to the default parameters

Parameters

colorWidth – Width of color resolution
colorHeight – High of color resolution
depthWidth – Width of depth resolution
depthHeight – High of depth resolution

Returns

OBCameraParam returns camera parameters

std::shared_ptr<StreamProfileList> getD2CDepthProfileList(std::shared_ptr<StreamProfile> colorProfile, OBAlignMode alignMode)

Return a list of D2C-enabled depth sensor resolutions corresponding to the input color sensor resolution.

Parameters

colorProfile – The input color sensor resolution
alignMode – The input align mode

Returns

std::shared_ptr<StreamProfileList> A list of depth sensor resolutions

OBRect getD2CValidArea(uint32_t minimumDistance, uint32_t maximumDistance = 0)

Get the valid area between the minimum distance and maximum distance after D2C.

Parameters

minimumDistance – The minimum working distance
maximumDistance – The maximum working distance (optional)

Returns

OBRect The area information valid after D2C at the working distance

void switchConfig(std::shared_ptr<Config> config)

Dynamically switch the corresponding config configuration.

Parameters: config – The updated config configuration

void startRecord(const char *filename)

Start recording.

Parameters: filename – The name of the record file

void stopRecord(): Stop recording.

class Playback

#include <RecordPlayback.hpp>

Public Functions

Playback(const char *filename)

Create a playback object.

Parameters: filename – The name of the playback file.

void start(PlaybackCallback callback, OBMediaType type = OB_MEDIA_ALL)

Start playback. The playback data is returned from the callback. Throws an exception on failure.

Parameters

callback – The callback for playback data.
type – The type of playback data.

void stop(): Stop playback. Throws an exception on failure.

void setPlaybackStateCallback(MediaStateCallback state)

Set the playback state.

Parameters: state – The playback status callback.

std::shared_ptr<DeviceInfo> getDeviceInfo()

Get the device information in the recording file.

Returns: DeviceInfo The device information.

OBCameraParam getCameraParam()

Get the intrinsic and extrinsic parameter in the recording file.

Returns: OBCameraParam Camera intrinsic and extrinsic parameter

class PointCloudFilter : public ob::Filter

#include <Filter.hpp>

The PointCloudFilter class is a subclass of Filter that generates point clouds.

Public Functions

void setCreatePointFormat(OBFormat type)

Set the point cloud type parameters.

Parameters: type – The point cloud type: depth point cloud or RGBD point cloud.

void setCameraParam(OBCameraParam param)

Set the camera parameters.

Parameters: param – The camera internal and external parameters.

void setFrameAlignState(bool state)

Set the frame alignment state that will be input to generate point cloud.

Parameters: state – The alignment status. True: enable alignment; False: disable alignment.

void setPositionDataScaled(float scale)

Set the point cloud coordinate data zoom factor.

Attention: Calling this function to set the scale will change the point coordinate scaling factor of the output point cloud frame: posScale = posScale / scale. The point coordinate scaling factor for the output point cloud frame can be obtained via PointsFrame::getPositionValueScale function.

Parameters: scale – The zoom factor.

void setColorDataNormalization(bool state)

Set point cloud color data normalization.

Parameters: state – Whether normalization is required.

void setCoordinateSystem(OBCoordinateSystemType type)

Set the point cloud coordinate system.

Parameters: type – The coordinate system type.

class PointsFrame : public ob::Frame

#include <Frame.hpp>

Public Functions

float getPositionValueScale()

Get the point position value scale of the points frame. The point position value of the points frame is multiplied by the scale to give a position value in millimeters. For example, if scale=0.1, the x-coordinate value of a point is x = 10000, which means that the actual x-coordinate value = x*scale = 10000*0.1 = 1000mm.

Returns: float The position value scale.

class Recorder

#include <RecordPlayback.hpp>

Public Functions

Recorder(): Create a recorder for data recording.

Recorder(std::shared_ptr<Device> device)

Create a recorder for data recording.

Parameters: device – The device for which to record device information.

void start(const char *filename, bool async = false)

Enable the recorder. Throws an exception on failure.

Parameters

filename – The name of the recorded file.
async – Whether to execute asynchronously.

void stop(): Stop the recorder. Throws an exception on failure.

void write(std::shared_ptr<Frame> frame)

Write frame data to the recorder.

Parameters: frame – The frame data to write.

class Sensor

#include <Sensor.hpp>

Public Functions

OBSensorType type()

Get the sensor type.

Returns: OBSensorType The sensor type.

const std::shared_ptr<StreamProfileList> getStreamProfileList()

Get the list of stream profiles.

Returns: std::shared_ptr<StreamProfileList> The stream profile list.

void start(std::shared_ptr<StreamProfile> streamProfile, FrameCallback callback)

Open a frame data stream and set up a callback.

Parameters

streamProfile – The stream configuration.
callback – The callback to set when frame data arrives.

void stop(): Stop the stream.

void switchProfile(std::shared_ptr<StreamProfile> streamProfile)

Dynamically switch resolutions.

Parameters: streamProfile – The resolution to switch to.

class SensorList

#include <Sensor.hpp>

Public Functions

uint32_t count()

Get the number of sensors.

Returns: uint32_t The number of sensors.

OBSensorType type(uint32_t index)

Get the type of the specified sensor.

Parameters: index – The sensor index.
Returns: OBSensorType The sensor type.

std::shared_ptr<Sensor> getSensor(uint32_t index)

Get a sensor by index number.

Parameters: index – The sensor index. The range is [0, count-1]. If the index exceeds the range, an exception will be thrown.
Returns: std::shared_ptr<Sensor> The sensor object.

std::shared_ptr<Sensor> getSensor(OBSensorType sensorType)

Get a sensor by sensor type.

Parameters: sensorType – The sensor type to obtain.
Returns: std::shared_ptr<Sensor> A sensor object. If the specified sensor type does not exist, it will return empty.

class StreamProfile : public std::enable_shared_from_this<StreamProfile>

#include <StreamProfile.hpp>

Subclassed by ob::AccelStreamProfile, ob::GyroStreamProfile, ob::VideoStreamProfile

Public Functions

OBFormat format() const

Get the format of the stream.

Returns: OBFormat return the format of the stream

OBStreamType type() const

Get the type of stream.

Returns: OBStreamType return the type of the stream

template<typename T> bool is()

Check if frame object is compatible with the given type.

Template Parameters: T – Given type
Returns: bool return result

template<typename T> inline std::shared_ptr<T> as()

Converts object type to target type.

Template Parameters: T – Target type
Returns: std::shared_ptr<T> Return the result. Throws an exception if conversion is not possible.

class StreamProfileList

#include <StreamProfile.hpp>

Public Functions

uint32_t count() const

Return the number of StreamProfile objects.

Returns: uint32_t Return the number of StreamProfile objects.

const std::shared_ptr<StreamProfile> getProfile(uint32_t index)

Return the StreamProfile object at the specified index.

Parameters: index – The index of the StreamProfile object to be retrieved. Must be in the range [0, count-1]. Throws an exception if the index is out of range.
Returns: std::shared_ptr<StreamProfile> Return the StreamProfile object.

const std::shared_ptr<VideoStreamProfile> getVideoStreamProfile(int width = 0, int height = 0, OBFormat format = OB_FORMAT_UNKNOWN, int fps = 0)

Match the corresponding video stream profile based on the passed-in parameters. If multiple Match are found, the first one in the list is returned by default. Throws an exception if no matching profile is found.

Parameters

width – The width of the stream. Pass 0 if no matching condition is required.
height – The height of the stream. Pass 0 if no matching condition is required.
format – The type of the stream. Pass OB_FORMAT_UNKNOWN if no matching condition is required.
fps – The frame rate of the stream. Pass 0 if no matching condition is required.

Returns

std::shared_ptr<VideoStreamProfile> Return the matching resolution.

const std::shared_ptr<AccelStreamProfile> getAccelStreamProfile(OBAccelFullScaleRange fullScaleRange, OBAccelSampleRate sampleRate)

Match the corresponding accelerometer stream profile based on the passed-in parameters. If multiple Match are found, the first one in the list is returned by default. Throws an exception if no matching profile is found.

Parameters

fullScaleRange – The full scale range. Pass 0 if no matching condition is required.
sampleRate – The sampling frequency. Pass 0 if no matching condition is required.

const std::shared_ptr<GyroStreamProfile> getGyroStreamProfile(OBGyroFullScaleRange fullScaleRange, OBGyroSampleRate sampleRate)

Match the corresponding gyroscope stream profile based on the passed-in parameters. If multiple Match are found, the first one in the list is returned by default. Throws an exception if no matching profile is found.

Parameters

fullScaleRange – The full scale range. Pass 0 if no matching condition is required.
sampleRate – The sampling frequency. Pass 0 if no matching condition is required.

class Version

#include <Version.hpp>

Public Static Functions

static int getMajor()

Get the major version number of the SDK.

Returns: int The major version number of the SDK.

static int getMinor()

Get the minor version number of the SDK.

Returns: int The minor version number of the SDK.

static int getPatch()

Get the patch version number of the SDK.

Returns: int The patch version number of the SDK.

static int getVersion()

Get the full version number of the SDK.

Returns: int The full version number of the SDK.

static char *getStageVersion()

Get the stage version of the SDK.

Returns: char* The stage version string of the SDK.

class VideoFrame : public ob::Frame

#include <Frame.hpp>

Subclassed by ob::ColorFrame, ob::DepthFrame, ob::IRFrame

Public Functions

uint32_t width()

Get the width of the frame.

Returns: uint32_t The width of the frame.

uint32_t height()

Get the height of the frame.

Returns: uint32_t The height of the frame.

void *metadata()

Get the metadata of the frame.

Returns: void* The metadata of the frame.

uint32_t metadataSize()

Get the size of the metadata of the frame.

Returns: uint32_t The size of the metadata of the frame.

uint8_t pixelAvailableBitSize()

Get the effective number of pixels in the frame.

Attention: Only valid for Y8/Y10/Y11/Y12/Y14/Y16 format.

Returns: uint8_t The effective number of pixels in the frame, or 0 if it is an unsupported format.

class VideoStreamProfile : public ob::StreamProfile

#include <StreamProfile.hpp>

Class representing a video stream profile.

Public Functions

uint32_t fps() const

Return the frame rate of the stream.

Returns: uint32_t Return the frame rate of the stream.

uint32_t width() const

Return the width of the stream.

Returns: uint32_t Return the width of the stream.

uint32_t height() const

Return the height of the stream.

Returns: uint32_t Return the height of the stream.